home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
The 640 MEG Shareware Studio 2
/
The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO
/
os2
/
pmgb202.zip
/
PMGLOBEX.DOC
< prev
next >
Wrap
Text File
|
1992-09-24
|
17KB
|
363 lines
PMGlobe -- an OS/2 Presentation Manager Globe -- Extended functions
===================================================================
Copyright (c) IBM Corporation, 1991, 1992.
PMGlobe commands, and how they are used
"""""""""""""""""""""""""""""""""""""""
This document lists the PMGlobe commands that are currently implemented.
These may be invoked from a PMGlobe macro (a program written in REXX),
or directly from the command dialog (which can be displayed by pressing
Escape while PMGlobe has the focus). The command dialog allows editing
of the command, using Insert, Delete, Backspace, and Cursor Left/Right;
it also has a simple 'retrieve' function, controlled by the Cursor
Up/Down keys.
To use commands from a macro, edit (perhaps with the OS/2 System Editor)
a plain ASCII file such as the TEST.PMG supplied with PMGlobe and
reproduced in part here:
/* Sample (test) macro */
/* Get the version information and set a new title */
'extract version versionb'
'set title PMGlobe -' version '('versionb'-bit)'
/* Mark and label some chosen cities */
"mark 51.5 0 label London"
"mark 37.8 -122.4 label San Francisco"
"mark -33.7 151.3 label Sydney"
This is a very simple REXX program that consists almost entirely of
commands (see SPIN.PMG for a more typical macro). After saving the
file, it can by run by simply bringing up the PMGlobe command dialog,
entering the name of the macro, and pressing Enter.
The 'Macros' checkbox on the command dialog means that macros will be
searched for before commands. If it isn't checked, the command "macro
xxxx", where "xxxx" is the name of the macro, will invoke it.
A macro can be called when PMGlobe is first started by specifying "MACRO
filename" as a parameter to the PMGlobe call, for example:
"start pmglobe macro mymacro"
Macro names as a parameter or on a command may include an explicit drive
and path, and if no extension is given then a default file extension of
".pmg" is added.
Note: all PMGlobe commands should currently be considered experimental;
**** the syntax and semantics of any command could change in future
versions of PMGlobe (if any).
General notes
"""""""""""""
-- Angles may be specified in decimal form, such as -30 or +45.5, where
for latitude and longitude negative implies south of the equator or
west of Greenwich respectively. The more usual format is also
allowed (for example: 52°30'10"E) -- details below. Angles
returned by QUERY or EXTRACT will always be in decimal form.
-- Times are specified and returned in seconds (with an optional sign
for relative times).
-- Keywords are shown below in capitals; they may be entered in mixed or
lower case.
-- Colors may also be in any case, and (with valid alternative spellings
in parentheses) must be one of: White Gray (Grey) Black Red Green
Blue Pink (Magenta) Cyan (Turquoise) Yellow DarkRed DarkGreen
DarkBlue Purple (DarkPink, DarkMagenta) DarkCyan (DarkTurquoise)
Brown. PaleGray (PaleGrey) is also allowed, for the Background color
only. The dark colors (from DarkRed onwards) cannot be used for Land
or Water coloring.
A QUERY or EXTRACT will return the first shown name for each color,
in uppercase.
-- The keyword "CENTER" may also be spelled as "CENTRE", and "COLOR"
as (or in) a keyword may be spelled "COLOUR".
-- It is recommended that long-running macros (especially those that use
the WAIT command) use the SET TITLE command to change the window
title to indicate that the macro is running. Good macros will also
allow for asynchronous alteration of viewpoint, etc., due to use of
the pull-down menus.
Commands in alphabetical order
""""""""""""""""""""""""""""""
CLOSE
Close PMGlobe (as though Close had been selected in the System menu).
EXTRACT items
Used for obtaining the values of various PMGlobe settings for use
with a REXX macro.
'Items' is a list of one or more keywords, as given in the QUERY and
SET commands below. The values of the specified items are placed into
REXX variables of the same name. (See above for a simple example.)
FONT name [SIZE height] [COLOR color] [FACE facename]
Defines a font, with nickname 'name'. SIZE sets the font size
(total height in points), and FACE specifies an OS/2 outline font
(e.g., "Helvetica", "Times New Roman", etc.). If no FACE is specified
then the default system proportional font and size is used, and SIZE
is ignored. The default size for all other fonts is 12 points. See
also the additional notes below.
The color for a font is specified using the COLOR keyword and one
of the colors listed above. The default color is Yellow.
Fonts may not be redefined. The default system proportional font is
predefined with the nickname 'Default'.
MACRO file [argumentstring]
Invoke the specified macro, a REXX program. The macro should be in
the working directory for the application, or have its path specified.
If no filename extension is given, one of ".pmg" is added. The
remainder of the command is passed as the argument to the macro
(accessible in REXX by the PARSE ARG instruction or ARG(1) built-in
function).
Note: At the highest level, macros run as a single separate thread.
Macros may invoke each other, using the MACRO command, up to a depth
of ten (other than this, only one macro can be running at a time).
All macros that are running will be halted by Ctrl-Break, or by
selecting 'Halt macro' from the menus or the command dialog.
MARK lat lon [MARKER m] [X x-offset] [Y y-offset] [CLOCK t-offset] [LABEL text]
MARK lat lon DELETE
Add or delete a mark to or from the displayed globe. Latitude and
Longitude (lat lon) are always required. If DELETE is used, the mark
must have been added before, and is deleted. If more than one mark
have the same latitude and longitude then the most recently added is
deleted.
If DELETE is not used, then a new mark is added. The point will be
marked according to the setting of of SET MARKER (default "+") at the
time of the MARK command, unless overridden by the option MARKER. The
value, m, of the marker can be any of ".", "+", "x", "X", or "OFF" for
various shapes of marker. "!" may be used for a tiny (single-pel)
marker.
The color used for a mark is the current drawing color, as set by 'SET
DRAWCOLOR color', at the time of the MARK command. If none was set
then White is used.
A mark may have a text associated with it, described by the CLOCK and
LABEL options. This text is displayed with the start of the baseline
at an offset from the mark as determined by the X and Y options; the
offsets are given in pels, up to 1000, and may be positive or
negative, or CENTER. The default X and Y offsets (x-offset and
y-offset) are +3. If the text would extend beyond the bounds of the
square enclosing the globe, then it is shifted in order to stay within
bounds (if possible).
If CLOCK is specified, t-offset describes the current GMT offset of
the mark in seconds, and the text begins with the time calculated
using this. This time is shown in 24-hour or civil format, depending
on the setting of CLOCKCIVIL, and is refreshed according to the
REFRESH setting. Use the CLOCKDAY setting for an additional
tomorrow/yesterday indication (+/-).
If LABEL is specified, it must be the last option on the command: the
remainder of the command, after the keyword LABEL and one blank, forms
the label part of the text, which follows any clock and may be up to
100 characters.
The font used for the text is the current font, as set by 'SET FONT
nickname', at the time of the MARK command. If none is set then the
default system font is used.
Markers, clocks, and labels can be included or excluded as a group by
using the MARKERS, CLOCKS, and LABELS settings. None of these are
shown if the window size is less than or equal to 64 pels in either
dimension (for example, if the globe is minimized to the desktop).
MESSAGE text
Display text in a message box. The message box can be moved, and does
not inhibit interaction with the globe or distance calculator. The
MESSAGE command waits until the "OK" pushbutton on the message box is
selected or the message box is closed. Commands are currently limited
to 200 characters, so the longest message possible is 192 characters.
REDRAW [ALL]
Initiates a redrawing of the Globe. Normally a REDRAW is automatic at
the end of a macro or (if the box on the dialog is checked) after a
command is entered from the command dialog. The REDRAW command is
provided for long-running macros. The command does not wait until
redrawing is complete.
The ALL option requests that all features of the globe are redrawn,
including any grid lines and marks (normally only those features that
have changed since the last draw are drawn).
QUERY items
Queries the state of various PMGlobe settings. 'items' is a list of
one or more keywords. Currently the result is displayed using
PMprintf; to see the results the PMprintf console must be active.
(PMprintf is an IBM developer's tool; if you do not have access to
this, use the EXTRACT command in a macro, followed by the MESSAGE
command to display values, etc.)
Any item that can be set by the SET command (see below) may also be
queried. The value of any item that may be set or queried may also be
obtained by a macro, using the EXTRACT command. PMprintf is not
needed in order to use these values in a macro.
Valid items are:
ACTIVE -- ON if the globe window is the active window, else OFF
CLOCKMARKS -- number of clocks set using the MARK command
DAYOFFSET -- time offset due to daylight savings (in seconds), or "UNKNOWN"
DIAMETER -- globe diameter in pels (0 if unknown)
FONTS -- number of fonts defined using the FONT command
GMTOFFSET -- base time offset from GMT (in seconds), or "UNKNOWN"
MARKS -- number of marks set using the MARK command
SUNLAT -- latitude at which sun is overhead (x.xxx), or "UNKNOWN"
SUNLON -- longitude at which sun is overhead (x.xxx), or "UNKNOWN"
(multiply by -4 to get time in minutes from solar noon)
VERSION -- PMGlobe version number
VERSIONB -- Version bits: always 32 for PMGLOBE2.EXE
ZONEABBREV -- timezone abbreviation (3 or 4 characters, or "???" if unknown)
SET item newvalue
Changes the state of various PMGlobe settings. Item is one of the
listed keywords. The value of any item that can be SET can also be
queried using the QUERY command, or obtained by a macro using the
EXTRACT command (see above).
Flags (items that are either ON or OFF) can also be set to INVERT,
which changes the state of the flag from ON to OFF or vice versa.
BACKCOLOR -- set the color of the background (names as given above)
CLOCKCIVIL -- use 12-hour clock format for any clocks (ON/OFF)
CLOCKDAY -- add flag (+ for tomorrow, - for yesterday) to clocks (ON/OFF)
CLOCKS -- display the clocks on marks (ON/OFF)
DESKTOP -- make PMGlobe the bottommost window (ON/OFF)
DRAWCOLOR -- set the color for drawing marks (names as given above)
ERRORBOX -- display command errors in a message box (ON/OFF)
FONT -- sets the current font, by nickname
GRIDCOLOR -- set the color of grid lines (names as given above)
GRIDLAT -- grid latitude line frequency (0/10/15/30/90)
GRIDLON -- grid longitude line frequency (0/10/15/30)
GRIDPOLAR -- show grid polar circles (ON/OFF)
GRIDTROPIC -- show grid tropics (ON/OFF)
IDLEDRAW -- draw map at low (IDLE+1) priority (ON/OFF)
LABELS -- display the labels on marks (ON/OFF)
LANDCOLOR -- set the color used for land at its brightest
MARGIN -- percentage border to allow around globe (0->49.999%)
MARKER -- current default marker (".", "+", "x", "X", or "OFF")
MARKERS -- display the markers on marks (ON/OFF)
REFRESH -- current refresh interval (in seconds, max 24 hours)
SHADING -- '3-D' shading (ON/OFF)
SHOWDRAW -- show (update) picture of globe as it is calculated (ON/OFF)
STARLIGHT -- 'star' lighting (ON/OFF) -- implies SUNLIGHT ON and SPACE ON
SUNLIGHT -- 'sun' lighting (ON/OFF)
SPACE -- 'earth from space' lighting (ON/OFF) -- implies SUNLIGHT ON
TITLE -- window and task list title (max 50 characters)
TWILIGHT -- degrees of twilight shown (max 18 degrees)
USEROFFSET -- time to add to real time (seconds, max +/- one year)
VIEWLAT -- latitude of center of view (x.xxx)
VIEWLON -- longitude of center of view (x.xxx)
WATERCOLOR -- set the color used for lakes and seas
The following settings are for development use only; the effect of
each is not defined:
DIAG -- send diagnostic messages to PMprintf (ON/OFF)
DIAGMSG -- display PM client messages to PMprintf (ON/OFF)
TEST -- controls certain test functions (ON/OFF)
WAIT [REDRAW] [time] [+time]
Wait until a redraw is completed, or until a particular time-of-day,
or for a certain length of time from now. "time" is in hours, with
optional minutes and seconds indicated by colons (for example, +0:20
would mean "wait for twenty minutes"). If a specific time of day is
given and is earlier than the current time of day, then the next day
is assumed. Multiple times (absolute, relative, or mixed) may be
specified, and WAIT will return when the earliest is reached. The
maximum wait time is 24 hours (+24).
If REDRAW is specified, then a REDRAW is started automatically, and
WAIT will return when the redraw is complete or any time condition
specified is met, whichever happens earlier.
Any WAIT is also ended by Ctrl-Break, or by selecting 'Halt macro'
from the menus or the command dialog.
Changing fonts
""""""""""""""
The fonts used for any clocks and labels on the MARK command can be
changed by first defining a new font (with the FONT command) and then
making the new font the current font (with the SET FONT command) before
issuing the MARK command.
The FONT command uses OS/2's facilities for choosing the 'nearest
outline font'; if no good match is found (for example, no font with the
specified face name exists) then the default system bitmap font is used.
The face name on a font definition should match the OS/2 font name for
an outline font exactly (for example "Helvetica", not "helvetica"). It
can be difficult to find a list of the fonts available; one way you may
be able to find one (if you have a printer installed) is to look at the
font installation panel for the printer driver you are using. (Click
mouse button 2 on the printer icon, then open Settings. Select the
Printer Driver page, then click button 2 on the driver icon and select
Settings again, then Fonts.) The following should always be available:
'Courier', 'Helvetica', 'Times New Roman', and 'Symbol Set'. The first
three of these may be followed by 'Bold', 'Italic', or 'Bold Italic'.
Example:
/* ORIGIN.PMG -- Show the origin in a Large font */
'font classic size 18 color red face Times New Roman Italic'
'set font classic'
'mark 0 0 y centre label The Origin'
Formats allowed for specifying degrees
""""""""""""""""""""""""""""""""""""""
A degree value may be specified in in degree-minutes-seconds format, or
in degree.decimal format.
If the degree value is specifying a latitude or longitude, then it
may be followed by one of the characters N, S, E, W (in either case),
as appropriate. The default is N (North) for latitude and E (East) for
longitude. A leading minus sign is allowed in either format, and negates
the direction implied by any N, E, S, or W. A leading plus sign is also
allowed; it has no effect.
No blanks are allowed: the seconds, or seconds and minutes, may
be omitted, as may be insignificant leading zeros. The syntax is
therefore one of:
[+|-][d]d[o[m]m['[s]s["]]][x]
[+|-][d]d[.[[d]d]d][x]
where the degree indicator in the first format may be either the letter
O (either case) or the true degree character (°, ASCII 248 on IBM PCs
and PS/2s).
Examples (all specifying a negative angle of 12 degrees 30 minutes):
-12.5 -12°30 12°30W 12°30'S
12°30'0"S -12°30'00N -12.500E 12o30s
----------
Mike Cowlishaw, IBM UK Laboratories